The Applicability Trap

"Duplication is always less expensive than bad abstraction"

BigCorp makes a new product, SUPERPLANE. It will have three variants: A, B, and C.

The SUPERPLANE publications department opts to use CCS techniques.

They create a "chunking" strategy based on SUPERPLANE’s requirements.

Each chunk or task can support multiple variants via conditional content (applicability), so the HANDBOOK SUPERPLANE A uses the same tasks as HANDBOOK SUPERPLANE B.

For example, one set of tasks is for the Wing System, and another set of tasks is for the Fuel System.

The tasks are produced and revisioned independent of the product variants.

Writers use conditions to specialize each of the tasks for the variant.

Efficiency is gained. Automated builds mean that each Product variant has the latest version of the documentation.

Hmm

Can you spot anything . . different?

It’s determined that SUPERPLANE D will also function as a car.

The Wing and Fuel systems will now be WingFuel System.

There are new systems to support ground travel.

SUPERPLANE D is the new baseline

but . .

SUPERPLANE B has Systems that do not work on SUPERPLANE D!

WingFuel System tasks are created - but new files don’t share change history with separate Wing and Fuel.

The history of Wing and Fuel tasks is lost for SuperPlane D.

This will cause problems with the FAR/FAA TC (type certification) process.

Conditional Directives for SUPERPLANE B can’t support SUPERPLANE D as the "new baseline". This causes publishing failures and content failures - the Grandfather Paradox in action.

This results in contract problems and airworthiness inspection issues, as our inspection procedures are no longer valid.

The conditional overhead in a typical task is now greater than the amount of content that is saved via de-duplication, due to complexity. The gains we sought have been eliminated.

Add costs of migration, implementation, plus fines, and costs of AOG (aircraft on ground).

This is the stuff that gets your publications system shut down, your department restructured, your boss fired, or every writer fired and references burnt for all time - basically setting your CV on fire.

Or all of the above.

AKA, digging ourselves out of this mess

Behind the scenes, SUPERPLANE D is classified as a separate Product - not a variant of SUPERPLANE.

A new "pseudo-variant" SUPERPLANE 0 is created to include the baseline parts from SUPERPLANE D - but NOT the new Systems.

The deliverable for SUPERPLANE D variant is folded back into SUPERPLANE fold post-processing, as a technical appendix in the deliverable.

This test can be automated for a codebase fairly easily.

These are not new problems. Issues with display (style), addressing (DMCs), and modification (applicability) were predicted as early as 1997 by architects working with transclusion in DynaText, Hytime, and SGML/DSSSL.

LaTeX and CommonMark emphatically rejected transclusion as a design goal due to necessarily domain semantics - precisely what we see with the Applicability Trap.

Variants live in a change system (as forks) or in an applicability model.

The Trap is a side effect from cumulative overhead of conditional logic - it’s agnostic of tools/markup.

CCS / CCMS techniques poor fit for product at Design or Prototype maturity without extremely active Maintainability, Logistics, and Support.

What’re your options?

Use unified (non-CCS) formats for prototype product.

That means one deliverable per variant. Lots of duplication, but no reliance on Systems, Configuration Management, etc.

Old-timey, sure. But old-timey works for a reason.

But sometimes you’re required to take the CCS path.

If CCS/CCMS is contractually required, Configuration Management and Maintainability must be active players in the CCS "chunking" (DMCs).

The same groups must also be active in planning Conditions (applic).

But you can’t force everyone to get on the boat.

If pubs HAS to "go it alone" AND has contractual requirements for CCS, THEN give the tasks their own variant code (S1000D SDC, DISCODEV, INCODEV)

ISOLATE until this . . whatever this is . . is mature.

Then merge back when it’s entered FRP (full rate production) - IF it ever shares content with anything else. Which it probably will not - it’s unarchitected.

Also, put the FAA on speed dial, because this is a huge red flag.